PlotIconSuite

PlotIconSuite
Header:	Icons.h		Carbon status:	Supported

Draws the icon described by an icon suite using the most appropriate icon in the suite for the current bit depth of the display device and the rectangle in which the icon is to be drawn.

OSErr PlotIconSuite (
    const Rect *theRect, 
    IconAlignmentType align, 
    IconTransformType transform, 
    IconSuiteRef theIconSuite
);

theRect

A pointer to the rectangle in which to draw the icon.

The function plots a single icon from the icon suite in the current graphics port. You cannot determine which icon from a given suite it will draw; the function bases this decision on the size of the specified destination rectangle and the current bit depth of the display device. For example, if the destination rectangle has the coordinates (100,100,116,116) and the display device is set to 4-bit color, the function draws the icon of type 'ics4' if that icon is available in the icon suite.

If the width or height of a destination rectangle is greater than or equal to 32 pixels, the function uses the 32-by-32 pixel icon with the appropriate bit depth for the display device. If the destination rectangle is less than 32 by 32 pixels and greater than 16 pixels wide or 12 pixels high, the function uses the 16-by-16 pixel icon with the appropriate bit depth. If the destination rectangle’s height is less than or equal to 12 pixels or its width is less than or equal to 16 pixels, the function uses the 12-by-16 pixel icon with the appropriate bit depth. (Typically, only the Finder and Standard File Package use 12-by-16 pixel icons.)

The destination rectangle passed in the theRect parameter must be exactly 32 by 32 pixels, 16 by 16 pixels, or 12 by 16 pixels for the function to draw the icon without stretching it. If the destination rectangle is not one of these standard sizes, the function expands or shrinks the icon to fit.

align

Specifies how the function should align the icon within the rectangle. For example, you can specify that the function center the icon within the rectangle or align it at one side or the other. See “Alignment Type Values” for a description of the values you can use here.

transform

Specifies how the function should modify the appearance of the icon. See “Transform Type Values” for a description of the values you can use here.

If you don’t specify a label constant in this parameter, the function displays the icon using the default label for that icon suite. When you create an icon suite using the GetIconSuite function or the NewIconSuite function, these functions set the default label for the suite to none. To set a new default label for an icon suite, use the SetSuiteLabel function.

theIconSuite

A handle to the icon suite from which the function gets the icon to draw. You can get a handle to an icon suite using the GetIconSuite or NewIconSuite functions.

function result: A result code.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.